The Compression Parameters Structure(IM: QC)

Inside Macintosh: QuickTime Components /

Chapter 4 - Image Compressor Components / Image Compressor Components Reference

The Compression Parameters Structure
Compressor components accept the parameters that govern a compression operation in the form of a data structure. This data structure is called a compression parameters structure. This structure is used by the CDBandCompress and CDPreCompress functions (described on page 4-63 and page 4-62, respectively).
The compression parameters structure is defined by the CodecCompressParams data type as follows:
typedef struct {
   ImageSequence           sequenceID;          /* sequence identifier ID
                                                   (precompress or 
                                                   bandcompress) */
   ImageDescriptionHandle  imageDescription;    /* handle to image
                                                   description structure
                                                   (precompress or
                                                    bandcompress) */
   Ptr                     data;                /* location for receipt of 
                                                   compressed image data */
   long                    bufferSize;          /* size of buffer for data */
   long                    frameNumber;         /* frame identifier */
   long                    startLine;           /* starting line for band */
   long                    stopLine;            /* ending line for band */
   long                    conditionFlags;      /* condition flags */
   CodecFlags              callerFlags;         /* control information
                                                   flags */
   CodecCapabilitiesPtr    *capabilities;       /* pointer to compressor
                                                   capability structure */
   ProgressProcRecord      progressProcRecord;  /* progress function
                                                   structure */
   CompletionProcRecord    completionProcRecord;/* completion function
                                                   structure */
   FlushProcRecord         flushProcRecord;     /* data-unloading function 
                                                   structure */
   PixMap                  srcPixMap;           /* pointer to image
                                                   (precompress or
                                                    bandcompress) */
   PixMap                  prevPixMap;          /* pointer to pixel map 
                                                   for previous image */
   CodecQ                  spatialQuality;      /* compressed image 
                                                   quality */
   CodecQ                  temporalQuality;     /* sequence temporal
                                                   quality */

   Fixed                   similarity;          /* similarity between 
                                                   adjacent frames */
   DataRateParamsPtr       dataRateParams;      /* data constraint
                                                   parameters */
   long                    reserved;            /* reserved */
} CodecCompressParams;
typedef CodecCompressParams *CodecCompressParamsPtr;
Field descriptions

sequenceID
Contains a unique sequence identifier. If the image to be compressed is part of a sequence, this field contains the sequence identifier that was assigned by the CompressSequenceBegin function. If the image is not part of a sequence, this field is set to 0.
imageDescription
Contains a handle to the image description structure that describes the image to be compressed.
data
Points to a location to receive the compressed image data. This is a 32-bit clean address--do not call StripAddress. If there is not sufficient memory to store the compressed image, the application may choose to write the compressed data to mass storage during the compression operation. The flushProc field identifies the data-unloading function that the application provides for this purpose.

This field is used only by the CDBandCompress function.
bufferSize
Contains the size of the buffer specified by the data field. Your component sets the value of the bufferSize field to the number of bytes of compressed data written into the buffer. Your component should not return more data than the buffer can hold--it should return a nonzero result code instead.

This field is used only by the CDBandCompress function.
frameNumber
Contains a frame identifier. Indicates the relative frame number within the sequence. The Image Compression Manager increments this value for each frame in the sequence.

This field is used only by the CDBandCompress function.
startLine
Contains the starting line for the band. This field indicates the starting line number for the band to be compressed. The line number refers to the pixel row in the image, starting from the top of the image. The first row is row number 0.

This field is used only by the CDBandCompress function.
stopLine
Contains the ending line for the band. This field indicates the ending line number for the band to be compressed. The line number refers to the pixel row in the image, starting from the top of the image. The first row in the image is row number 0.

The image band includes the row specified by this field. So, to define a band that contains one row of pixels at the top of an image, you set the startLine field to 0 and the stopLine field to 1.
conditionFlags
Contains flags that identify the condition under which your component has been called. This field is used only by the CDBandCompress function. In addition, these fields contain information about actions taken by your component. Condition flags fields contain the following flags:
              #define codecConditionFirstBand      (1L<<0)     
              #define codecConditionLastBand       (1L<<1)
The codecConditionFirstBand constant is an input flag that indicates if this is the first band in the frame. If this flag is set to 1, then your component is being called for the first time for the current frame.

The codecConditionLastBand constant is an input flag that indicates if this is the last band in the frame. If this flag is set to 1, then your component is being called for the last time for the current frame. If the codecConditionFirstBand flag is also set to 1, this is the only time the Image Compression Manager is calling your component for the current frame.
The codecConditionCodecChangedMask constant is an output flag that indicates that the component has changed the mask bits. If your image decompressor component can mask decompressed images and if some of the image pixels should not be written to the screen, set to 0 the corresponding bits in the mask defined by the maskBits field in the decompression parameter structure. In addition, set this flag to 1. Otherwise, set this flag to 0.

callerFlags
The callerFlags constant is an output flag that contains flags providing further control information. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for information about the Image Compression Manager function control flags. The following flags are available:
codecFlagUpdatePrevious
Controls whether your compressor updates the previous image during compression. This flag is only used with sequences that are being temporally compressed.
If this flag is set to 1, your compressor should copy the current frame into the previous frame buffer at the end of the frame-compression sequence. Use the source image.
codecFlagWasCompressed
Indicates to your compressor that the image to be compressed has been compressed before. This information may be useful to compressors that can compensate for the image degradation that may otherwise result from repeated compression and decompression of the same image. This flag is set to 1 to indicate that the image was previously compressed. This flag is set to 0 if the image was not previously compressed.
codecFlagUpdatePreviousComp
Controls whether your compressor updates the previous image buffer with the compressed image. This flag is only used with temporal compression. If this flag is set to 1, your compressor should update the previous frame buffer at the end of the frame-compression sequence, allowing your compressor to perform frame differencing against the compression results. Use the image that results from
the compression operation. If this flag is set to 0,
your compressor should not modify the previous frame buffer during compression.
codecFlagLiveGrab
Indicates whether the current sequence results from grabbing live video. When working with live video, your compressor should operate as quickly as possible and disable any additional processing, such as compensation for previously compressed data. This flag is set to 1 when you are compressing from a live video source.

This field is used only by the CDBandCompress function (described on page 4-63).
capabilities
Points to a compressor capability structure. The Image Compression Manager uses this field to determine the capabilities of your compressor component.

This field is used only by the CDPreCompress function (described on page 4-62).
progressProcRecord
Contains a progress function structure. During the compression operation, your compressor may occasionally call a function that the application provides in order to report your progress (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about progress functions). This field contains a structure that identifies the progress function. If the progressProc field in this structure is set to nil, the application has not supplied a progress function.

This structure is used only by the CDBandCompress function (described on page 4-63).
completionProcRecord
Contains a completion function structure. This structure governs whether you perform the compression asynchronously. If the completionProc field in this structure is set to nil, perform the compression synchronously. If this field is not nil, it specifies an application completion function. Perform the compression asynchronously and call that completion function when your component is finished. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for information on calling completion functions. If the completionProc field in this structure has a value of -1, perform the operation asynchronously but do not call the application's completion function.

This structure is used only by the CDBandCompress function.
flushProcRecord
Contains a data-unloading function structure. If there is not enough memory to store the compressed image, the application may provide a function that unloads some of the compressed data (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about data-unloading functions). This field contains a structure that identifies that data-unloading function.

If the application did not provide a data-unloading function, the flushProc field in this structure is set to nil. In this case, your component writes the entire compressed image into the memory location specified by the data field.

The data-unloading function structure is defined by the flushProcRecord data type as follows:
               struct FlushProcRecord {
                  FlushProcPtr flushProc; /* pointer to 
                                             data-unloading
                                             function */
                  long flushRefCon;     /* data-unloading
                                             function reference
                                             constant */
               };
               typedef struct FlushProcRecord FlushProcRecord;
               typedef FlushProcRecord *FlushProcRecordPtr;
The data-unloading function structure is used only by the CDBandCompress function (described on page 4-63).
srcPixMap
Points to the image to be compressed. The image must be stored in a pixel map structure. The contents of this pixel map differ from a standard
pixel map in two ways. First, the rowBytes field is a full 16-bit
value--the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address.

This field is used only by the CDBandCompress function.
prevPixMap
Points to a pixel map containing the previous image. If the
image to be compressed is part of a sequence that is being temporally compressed, this field defines the previous image
for temporal compression. Your component should then use this previous image as the basis of comparison for the image to be compressed.

If the temporalQuality field is set to 0, do not perform temporal compression. If the codecFlagUpdatePrevious flag or the codecFlagUpdatePreviousComp flag in the flags field is set to 1, update the previous image at the end of the compression operation.

The contents of this pixel map differ from a standard pixel map in two ways. First, the rowBytes field is a full 16-bit value--the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address.

This field is used only by the CDBandCompress function.
spatialQuality
Specifies the desired compressed image quality. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values.

This field is used only by the CDBandCompress function.

Check to see if the value of this parameter is nil and, if so, do not write to location 0.
temporalQuality
Specifies the desired sequence temporal quality. This field governs the level of compression the application desires with respect to information in successive frames in the sequence. If this field is set to 0, do not perform temporal compression on this frame. See the chapter "Image Compression Manger" in Inside Macintosh: QuickTime for other available values.

This field is used only by the CDBandCompress function (described on page 4-63).

Check to see if the value of this parameter is nil and, if so, do not write to location 0.
similarity
Indicates the similarity between adjacent frames when performing temporal compression. Your component returns a fixed-point number in this field. That value indicates the relative similarity between the frame just compressed and the previous frame. Valid values range from 0 (key frame) to 1 (identical).

This field is used only by the CDBandCompress function.

Check to see if the value of this parameter is nil and, if so, do not write to location 0.
dataRateParams
Points to the parameters used when performing data rate constraint.
reserved
Reserved for use by Apple.